source-code-brainstorming

From Microformats Wiki
(Redirected from source-brainstorming)
Jump to navigation Jump to search

Per the microformats process, this page is for brainstorming about ideas, proposals, constraints, requirements for a microformat for indicating the link relationship between a document (or site) and its source code.

Background research:

Alternatives

Summary of prior (pre-2025) brainstorm alternatives:

  • rel=source. Good: short, covers lots of use-cases. Bad: ambiguous term. could be better used to define a source where the information came from. When someone writes an article, which is based on information from somewhere else, rel="source" would be a more appropriate name.
  • rel=code. Good: clearly express a semantic for "the code for the current page is over there". Issues: which code? The HTML, the PHP, something else? Re-proposed in IndieWeb dev chat 2025-05-25
  • rel=sourcecode. Good: more specific than others. Bad: naming is less readable with two adjacent words.

2025+ brainstorming additions:

  • rel=source-code. Good: better than "sourcecode". Bad: Longer than "code" with no discernible benefit.
  • rel=repository. Good: more precise semantic for just the (presumably revision control) repository file for the current page, without asserting a 'code' semantic. From IndieWeb dev chat 2025-05-25. Alternatives:
    • rel=repo. Advantage: shorter. Disadvantage: less obvious.
    • rel=vcs. Advantage: even shorter. Disadvantage: acronym, even less obvious.
  • rel="code repository" to link to the code file for a page in a repository. Good: combine multiple precise semantics to express an even more precise semantic. From IndieWeb dev chat 2025-05-25.
  • rel="directory repository" to link to the folder of the file for a page, in a repository, re-using pre-existing rel-directory semantics. From IndieWeb dev chat 2025-05-25.
  • rel="repository root" (order doesn't matter), or rel="repository home" to link to the repository root (or home) for the file for the current page. From IndieWeb dev chat 2025-05-25.
  • rel="edit repository" links to the edit state of the file for the current page, in a repository so you can immediately start typing into the text area, in contrast to say plain rel="edit" for when linking to the edit state locally on the page itself like on a MediaWiki install (Wikipedia etc.) that directly shows you a textarea to edit the page you are viewing. Good: similar combination of multiple precise semantics to express both. From IndieWeb dev chat 2025-05-25.
  • ...

Potential algorithm for finding a representative URL for editing/viewing source

A UX pattern relevant to the proposed rels above is to find the URL that has the highest combination of specificity given the user's privilege.

An algorithm for parsing could be:

  • Find all link then a tags that contain the edit rel value.
    • Return the first matching link tag found. If none found, return the first matching a tag found. Else, go onto the next step.
  • Find all link and a tags that contain rel values of both code and repository. Return the first one found. Else, go onto the next step.
    • Return the first matching link tag found. If none found, return the first matching a tag found. Else, go onto the next step.
  • Find all link and a tags that contain the code rel attribute.
    • Return the first matching link tag found. If none found, return the first matching a tag found. Else, go onto the next step.
  • Find all link and a tags that contain have rel values of both directory and repository.
    • Return the first matching link tag found. If none found, return the first matching a tag found. Else, go onto the next step.
  • Find all link and a tags that contain the directory rel attribute.
    • Return the first matching link tag found. If none found, return the first matching a tag found. Else, go onto the next step.
  • Find all link and a tags that contain have rel values of both home and repository.
    • Return the first matching link tag found. If none found, return the first matching a tag found. Else, go onto the next step.
  • Find all link and a tags that contain have rel values of both root and repository.
    • Return the first matching link tag found. If none found, return the first matching a tag found. Else, go onto the next step.
  • If no links are found, return null.

In addition, a check should be done against the HTTP Link> headers using the same order of precedence as outlined above:

  • edit
  • code repository
  • code directory
  • home repository
  • root repository

repository is a modifier that may appear at any point in a rel value.

Needs refactoring

ℹ️ Note: The rest of this page needs some analysis and refactoring, moving e.g. "examples demonstrate situations where an explicit rel value could be used" to the source-code-examples page

Usage

<a href="https://github.com/adactio/html5forwebdesigners" rel="source">the source for this book</a>
<link href="https://github.com/adactio/html5forwebdesigners" rel="source" />

Use Cases

When an author links to a project's (or document's) source code (e.g. on GitHub, Google Code, etc.) a rel value of "source" could be used to explicitly define that relationship.

Discussions

rel="code"

source could be better used to define a source where the information came from. When someone writes an article, which is based on informations somewhere else, rel="source" would be a more appropriate name.

Better naming recommendations for the case of this rel-Attribute:

  1. code
  2. sourcecode

Use when linking to project source code

Could this really be used to link to a project’s (rather than the current document’s) source code?

Using the Unison.js example, with all HTML attributes removed except rel and href: 

<a rel="source" href="https://github.com/bjork24/Unison">View on GitHub</a>

Following the rel-faq, this would be interpreted as:

The resource indicated by https://github.com/bjork24/Unison is a "source" for the current document.

But it isn’t. The Unison.js project page on responsivedesign.is does not seem to use Unison.js in any way.

Related post:

Relations between one URI and a linked URI

To think about the relations in between the current resource (URI) and the linked one, a way is to imagine what would be the "title" attribute that would help users take an action on the link. Basically, we are telling something along the line: "Explore the hosted source code of this project we are talking about on this page." The relation between this current resource I'm reading and the resource I'm linking to is more of a "owl:seeAlso" aka additional information, but it's not really a relation which is related to the source code. In the past, it would have been simply "download the gzipped tarball". Maybe there is no real usage for a meaningful "rel" value.

Examples

These examples demonstrate situations where an explicit rel value could be used to mark up an existing document (or project's) link to its source.

See Also

Retrieved from "http://microformats.org/wiki/index.php?title=source-code-brainstorming&oldid=70809"